Internally, storage for 1 bit images is 1 byte per pixel:

1 bit images are shuffled at import/export to put them in this format.

Interesting! I didn't expect tobytes to return something other than how the data is stored internally. The documentation of tobytes does say so:

This method returns the raw image data from the internal storage

That documentation also says to look at _imaging.c so I followed the white rabbit up to Pack.c and found out that even the raw encoder can actually use multiple packing functions, that's super cool! I've seen cases where custom serialization of individual channels or postprocessing of tobytes was done to encode e.g. pixels in BGR format, while tobytes("raw", "BGR") would have been enough and much more efficient. I guess documenting all of these special packers would be daunting; but pointing at Pack.c and giving a couple examples could be very useful.

And in any case, I still think the two sentences (the "one pixel per byte" and the "tobytes returns raw data") are very misleading when taken together. I would still suggest to remove the first sentence. I think it's better to not give any expectations than provide false expectations.

Yeah, tobytes has a lot behind it because of the packer infrastructure. "Returns raw image data" is mostly true, at least for most modes in the default raw configuration. It's more true than running image.save into a BytesIO object.

I suspect that the 1 bit thing is just one of those historical choices -- it's a lot easier to do math in 1 pixel per byte than one per bit, especially when you already have that math implemented for other modes. Historically it's tripped up people with the array/numpy integration, and this is effectively the one way you can get 1 bit/pixel out of a mode 1 image.

This method returns the raw image data from the internal storage.

The origin of this sentence was in #1470, where one user wanted to clarify that tobytes() didn’t return data in a regular image format. It’s unfortunate that one clarification has lead to different confusion.

i think ‘raw image data' is intended to mean one-dimensional pixel data without context, and ‘from the internal storage’ is intended to mean ‘this isn’t the form the data had in any given file’

I think it's better to not give any expectations than provide false expectations.

As a general principle, I'm in favour of clarifying information. I'm not in favour of removing information because it might be misunderstood.

I think 'stored with one pixel per byte' is meant to communicate that Pillow will use more memory than you might expect.

This is kind of a specific situation to document - not so much because of the 1 mode, but because what you’re talking about just the “raw” encoder, and tobytes() can be used with other encoders. If you used any other encoder, I think it would be clearer what you received wasn't exactly what was stored internally in Pillow.

And interestingly, when this specific situation does become relevant to Pillow's internal code, there is a comment that tries to explain your scenario.

I've created #8878 as an alternative - it leaves in the information about how mode 1 image data is stored, mentions that tobytes() returns data derived from internal storage, and adds a reference to Pack.c.

Great, thank you. I'll close this PR in favor of the new one.